Introduction

This team exercise has five tasks:

  1. Create a GitHub Pull Request
  2. Perform a Code Review of the PR
  3. Fill-in the Code Review Document
  4. Add Code Review to the Definition of Done
  5. Submit Document to myCourses Dropbox
This is a team-based activity for the Term Project. You need to do this activity as a team. Spend in the range of 30 minutes performing the code review and filling-in the supplied document.

Task 1: Create a GitHub Pull Request

One team member should perform this step.

  1. Create a new pull request.
    The GitHub Home page for the Guessing Game.
    1. Navigate to the GitHub home page for you Project.
    2. Select the Pull requests tab.
    3. Click on the New pull request button.
  2. Select the feature branch.
    The Pull Request creation page.
    1. Leave the "base" dropdown on master.
    2. Select the feature branch "compare" dropdown.
    3. Click on the Create pull request button.
  3. Edit the pull request.
    The Pull Request creation page.
    1. Enter a description with the Story text and the list of acceptance criteria.
      GitHub uses Markdown so you can create headings and italic styling and list. Use the Preview tab to see how the Markdown looks.
    2. Add reviewers to the pull request.
      Click on the Reviewers label to add reviewers.
      • The Suggestions list should show your team members.
      • You can also use the text-field to enter a user's username.
      • For this activity add every team member and your instructor.
        Future code reviews will not likely include all team members.
      • When everyone has been entered you can close this dialog box.
    3. Click on the Create pull request button to create the PR.

Task 2: Perform a Code Review on the PR

After the PR is created each reviewer will receive an email notification with a link to the PR. This is the starting point of the code review. Basically, each reviewer reads through the code changes and enters comments at a specific line of code. The developer (owner of the PR) can reply to the comments and start a thread of conversation. The steps below walk you through one specific exchange between two developers.

  1. A reviewer opens the pull request.
    1. Use the link in the email to navigate to the pull request.
      There are three tabs; the Conversation tab is the default; it shows the PR description and the history of comments and replies. The Commits tab shows all commit points of the branch. The Files changed tab shows the diffs view of all of the file changes.
    2. Select the Files changed tab.
      This view has every file listed in alphabetic order, including directory paths; so for example, production code in src/main/ comes before the testing code in src/test/.
    3. Scroll up and down to review each file.
  2. A reviewer adds a comment.
    1. Point and click a line of the file most relevant to the issue.
      In this scenario the gamesPlayed and gamesWon variables hold data that is separated from the functionality. In this code chunk these values are updated and the end of a single game. Further down in this code is the new getMyGameStatsMessage method. This is also part of the "behavior" of this data.
    2. The UI displays the comment editor panel.
      Use the Markdown editor to enter the comment. Here the reviewer is suggesting that this data should be encapsulated.
    3. Click the Add single comment button to submit the comment.
  3. The developer replies to the comment.
    When the reviewer submits a comment the GitHub UI will notify the developer that there are new comments. The person can then refresh there pull request page to see the new comments.
    1. The developer refreshes the page and sees the reviewer's comment.
    2. The developer replies to the comment.
      Use the Markdown editor (again) to enter the reply.
  4. The conversation can continue until a resolution is found.
    A complete code review conversation.
    At this point it is up to the developer to refactor the code based upon the agreed re-design. Any changes that get pushed to this branch will be incorporated into the pull request and will be visible in this user interface. Thus pull requests may evolve over time.

Task 3: Fill-in the Code Review Document

Download the attached Code Review template file. Fill-in a row in the Code Review grid for each violation found in the pull request. Spend in the range of 30 minutes on this portion of the activity.

This sample Code Review file shows a review of the Guessing Game Story 1 feature.

Task 4: Add Code Review to the Definition of Done

From this point forward, every story should have a code review so add perform code review to the Definition of Done checklist in the USER STORY template. So up to this lesson your checklist should look like this:

The Definition of Done checklist template.

To clarify, after a story is code complete, and the design documentation is updated, the developer will create a pull request for this story and move the story card into the Ready for Test Trello list. At that point, manual acceptance testing and review of the pull request can occur in parallel.

In case I have to state the obvious: The developer(s) of a given feature must not be the one to either do acceptance testing nor the code review. Also, ideally it would be good to have at least two developers do the review.

Task 5: Submit Document to MyCourses Dropbox

Rename the document to Team X - Code Review.docx, where X is the capital letter for your team. Submit the file to the Code Review Dropbox in MyCourses before the due date specified in your section's schedule.